Skip to content

fix: ensure that @Nullable does not incorrectly affect object schemas#5124

Open
Mattias-Sehlstedt wants to merge 3 commits into
swagger-api:masterfrom
Mattias-Sehlstedt:do-not-set-nullable-on-objects
Open

fix: ensure that @Nullable does not incorrectly affect object schemas#5124
Mattias-Sehlstedt wants to merge 3 commits into
swagger-api:masterfrom
Mattias-Sehlstedt:do-not-set-nullable-on-objects

Conversation

@Mattias-Sehlstedt

@Mattias-Sehlstedt Mattias-Sehlstedt commented Apr 11, 2026

Copy link
Copy Markdown
Contributor

Pull Request

Thank you for contributing to swagger-core!

Please fill out the following information to help us review your PR efficiently.


Description

Changes so that a @Nullable annotation present on a model does not incorrectly set type: null for OAS 3.1 or nullable: true for OAS 3.0. The nullable is instead dropped entirely. This since the resolving currently does not support an easy way of expressing nullable with refs correctly as per:
OAS3.0

{ "nullable": true, "allOf": [{ "$ref": "#/components/schemas/NestedObject" }] }

or
OAS3.1

{ "oneOf": [{ "$ref": "#/components/schemas/NestedObject" }, { "type": "null" }] }

Fixes: #5115

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • ♻️ Refactor (non-breaking change)
  • 🧪 Tests
  • 📝 Documentation
  • 🧹 Chore (build or tooling)

Checklist

  • I have added/updated tests as needed
  • I have added/updated documentation where applicable
  • The PR title is descriptive
  • The code builds and passes tests locally
  • I have linked related issues (if any)

Screenshots / Additional Context

@ewaostrowska ewaostrowska force-pushed the do-not-set-nullable-on-objects branch from 43c78f7 to 76491e1 Compare June 18, 2026 10:51
@ewaostrowska

Copy link
Copy Markdown
Contributor

@Mattias-Sehlstedt thank you for taking your time to work on this issue!

I do agree that fixing #5077 under no circumstances should introduce #5115. I have extended your PR to try to cover both of these issues. The commit preserves the nullable by wrapping the property's $ref at resolution time: oneOf for OAS 3.1 and nullable:true + allOf for OAS 3.0. The component schema should remain type:object and not be affected.

@Mattias-Sehlstedt

Copy link
Copy Markdown
Contributor Author

Due to my experience with tooling tied to OAS I would suggest that the implementation of wrapNullableRef be split into a separate issue and then be implemented as a feat-commit (same as what I suggested here). This since many tools might not handle nullable ref:s at all, and that might lead to people raising even more issue).

There is also the issue that for OAS 3.1., there are many "correct" ways of expressing nullable ref:s. So to better capture this one could preferably have a more semi-formal feat that explained what has been introduced and why (and the basis for the choice of how nullable ref:s are expressed in OAS 3.1).

So the new issue would capture why and how, but it could also ensure that wrapNullableRef is made as a protected method, so that if anyone believes "it should be a type array and not oneOf with a null child", then we could instantly direct them to the option "Then you can override wrapNullableRef with your preferred behavior" (or disable it altogether easily as well). Similar to what was done here to easily give the user the possibility to inject small behavioral changes if they want to.

So we would keep this PR as a simple "prevent accidental leakage of @Nullable for objects introduce in #5018", which would just restore expected and previous behavior. And the real behavior-change is then tracked and explained in isolation and clarity.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: @Nullable annotation incorrectly affects object and sets the type to null

2 participants